.TH std::basic_string 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_string \- std::basic_string

.SH Synopsis
   Defined in header <string>
   template<

       class CharT,
       class Traits = std::char_traits<CharT>,                        \fB(1)\fP
       class Allocator = std::allocator<CharT>

   > class basic_string;
   namespace pmr {

   template<
       class CharT,
       class Traits = std::char_traits<CharT>                         \fB(2)\fP \fI(since C++17)\fP
   > using basic_string =
       std::basic_string<CharT, Traits,
   std::pmr::polymorphic_allocator<CharT>>;

   }

   The class template basic_string stores and manipulates sequences of character-like
   objects, which are non-array objects of TrivialType and StandardLayoutType. The
   class is dependent neither on the character type nor on the nature of operations on
   that type. The definitions of the operations are supplied via the Traits template
   parameter - a specialization of std::char_traits or a compatible traits class.

   The elements of a basic_string are stored contiguously, that is, for a basic_string
   s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, s.size())
   , and *(s.begin() + s.size()) has value CharT() (a null terminator)
   \fI(since C++11)\fP; or, equivalently, a pointer to s[0] can be passed to functions that
   expect a pointer to the first element of
   an array
   \fI(until C++11)\fP
   a null-terminated array
   \fI(since C++11)\fP of CharT.

   std::basic_string satisfies the requirements of AllocatorAwareContainer (except that
   customized construct/destroy are not used for construction/destruction of elements),
   SequenceContainer
   and ContiguousContainer
   \fI(since C++17)\fP.

   If any of Traits::char_type and Allocator::char_type is different from CharT, the
   program is ill-formed.

   Member functions of std::basic_string are constexpr: it is possible to
   create and use std::string objects in the evaluation of a constant
   expression.
                                                                          \fI(since C++20)\fP
   However, std::string objects generally cannot be constexpr, because
   any dynamically allocated storage must be released in the same
   evaluation of constant expression.

   Several typedefs for common character types are provided:

   Defined in header <string>
   Type                        Definition
   std::string                 std::basic_string<char>
   std::wstring                std::basic_string<wchar_t>
   std::u8string (C++20)       std::basic_string<char8_t>
   std::u16string \fI(C++11)\fP      std::basic_string<char16_t>
   std::u32string \fI(C++11)\fP      std::basic_string<char32_t>
   std::pmr::string \fI(C++17)\fP    std::pmr::basic_string<char>
   std::pmr::wstring \fI(C++17)\fP   std::pmr::basic_string<wchar_t>
   std::pmr::u8string (C++20)  std::pmr::basic_string<char8_t>
   std::pmr::u16string \fI(C++17)\fP std::pmr::basic_string<char16_t>
   std::pmr::u32string \fI(C++17)\fP std::pmr::basic_string<char32_t>

.SH Template parameters

   CharT     - character type
   Traits    - traits class specifying the operations on the character type
   Allocator - Allocator type used to allocate internal storage

.SH Member types

   Member type            Definition
   traits_type            Traits
   value_type             CharT
   allocator_type         Allocator
                          Allocator::size_type                        \fI(until C++11)\fP
   size_type              std::allocator_traits<Allocator>::size_type \fI(since C++11)\fP


                          Allocator::difference_type                        (until
                                                                            C++11)
   difference_type        std::allocator_traits<Allocator>::difference_type (since
                                                                            C++11)


   reference              value_type&
   const_reference        const value_type&
                          Allocator::pointer                        \fI(until C++11)\fP
   pointer                std::allocator_traits<Allocator>::pointer \fI(since C++11)\fP


                          Allocator::const_pointer                        \fI(until C++11)\fP
   const_pointer          std::allocator_traits<Allocator>::const_pointer \fI(since C++11)\fP


                          LegacyRandomAccessIterator and                  \fI(until C++20)\fP
                          LegacyContiguousIterator to value_type
                          LegacyRandomAccessIterator,
   iterator               contiguous_iterator, and ConstexprIterator to   \fI(since C++20)\fP
                          value_type


                          LegacyRandomAccessIterator and                  \fI(until C++20)\fP
                          LegacyContiguousIterator to const value_type
                          LegacyRandomAccessIterator,
   const_iterator         contiguous_iterator, and ConstexprIterator to   \fI(since C++20)\fP
                          const value_type


   reverse_iterator       std::reverse_iterator<iterator>
   const_reverse_iterator std::reverse_iterator<const_iterator>

.SH Member functions

   constructor                constructs a basic_string
                              \fI(public member function)\fP
                              destroys the string, deallocating internal storage if
   destructor                 used
                              \fI(public member function)\fP
   operator=                  assigns values to the string
                              \fI(public member function)\fP
   assign                     assign characters to a string
                              \fI(public member function)\fP
   assign_range               assign a range of characters to a string
   (C++23)                    \fI(public member function)\fP
   get_allocator              returns the associated allocator
                              \fI(public member function)\fP
.SH Element access
   at                         accesses the specified character with bounds checking
                              \fI(public member function)\fP
   operator[]                 accesses the specified character
                              \fI(public member function)\fP
   front                      accesses the first character
   (DR*)                      \fI(public member function)\fP
   back                       accesses the last character
   (DR*)                      \fI(public member function)\fP
   data                       returns a pointer to the first character of a string
                              \fI(public member function)\fP
                              returns a non-modifiable standard C character array
   c_str                      version of the string
                              \fI(public member function)\fP
   operator basic_string_view returns a non-modifiable string_view into the entire
   \fI(C++17)\fP                    string
                              \fI(public member function)\fP
.SH Iterators
   begin                      returns an iterator to the beginning
   cbegin                     \fI(public member function)\fP
   \fI(C++11)\fP
   end                        returns an iterator to the end
   cend                       \fI(public member function)\fP
   \fI(C++11)\fP
   rbegin                     returns a reverse iterator to the beginning
   crbegin                    \fI(public member function)\fP
   \fI(C++11)\fP
   rend                       returns a reverse iterator to the end
   crend                      \fI(public member function)\fP
   \fI(C++11)\fP
.SH Capacity
   empty                      checks whether the string is empty
                              \fI(public member function)\fP
   size                       returns the number of characters
   length                     \fI(public member function)\fP
   max_size                   returns the maximum number of characters
                              \fI(public member function)\fP
   reserve                    reserves storage
                              \fI(public member function)\fP
                              returns the number of characters that can be held in
   capacity                   currently allocated storage
                              \fI(public member function)\fP
   shrink_to_fit              reduces memory usage by freeing unused memory
   (DR*)                      \fI(public member function)\fP
.SH Modifiers
   clear                      clears the contents
                              \fI(public member function)\fP
   insert                     inserts characters
                              \fI(public member function)\fP
   insert_range               inserts a range of characters
   (C++23)                    \fI(public member function)\fP
   erase                      removes characters
                              \fI(public member function)\fP
   push_back                  appends a character to the end
                              \fI(public member function)\fP
   pop_back                   removes the last character
   (DR*)                      \fI(public member function)\fP
   append                     appends characters to the end
                              \fI(public member function)\fP
   append_range               appends a range of characters to the end
   (C++23)                    \fI(public member function)\fP
   operator+=                 appends characters to the end
                              \fI(public member function)\fP
   replace                    replaces specified portion of a string
                              \fI(public member function)\fP
   replace_with_range         replaces specified portion of a string with a range of
   (C++23)                    characters
                              \fI(public member function)\fP
   copy                       copies characters
                              \fI(public member function)\fP
   resize                     changes the number of characters stored
                              \fI(public member function)\fP
                              changes the number of characters stored and possibly
   resize_and_overwrite       overwrites indeterminate contents via user-provided
   (C++23)                    operation
                              \fI(public member function)\fP
   swap                       swaps the contents
                              \fI(public member function)\fP
.SH Search
   find                       finds the first occurrence of the given substring
                              \fI(public member function)\fP
   rfind                      find the last occurrence of a substring
                              \fI(public member function)\fP
   find_first_of              find first occurrence of characters
                              \fI(public member function)\fP
   find_first_not_of          find first absence of characters
                              \fI(public member function)\fP
   find_last_of               find last occurrence of characters
                              \fI(public member function)\fP
   find_last_not_of           find last absence of characters
                              \fI(public member function)\fP
.SH Operations
   compare                    compares two strings
                              \fI(public member function)\fP
   starts_with                checks if the string starts with the given prefix
   (C++20)                    \fI(public member function)\fP
   ends_with                  checks if the string ends with the given suffix
   (C++20)                    \fI(public member function)\fP
   contains                   checks if the string contains the given substring or
   (C++23)                    character
                              \fI(public member function)\fP
   substr                     returns a substring
                              \fI(public member function)\fP
.SH Constants
   npos                       special value. The exact meaning depends on the context
   \fB[static]\fP                   \fI(public static member constant)\fP

.SH Non-member functions

   operator+                    concatenates two strings or a string and a char
                                \fI(function template)\fP
   operator==
   operator!=
   operator<
   operator>
   operator<=
   operator>=                   lexicographically compares two strings
   operator<=>                  \fI(function template)\fP
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (removed in C++20)
   (C++20)
   std::swap(std::basic_string) specializes the std::swap algorithm
                                \fI(function template)\fP
   erase(std::basic_string)     erases all elements satisfying specific criteria
   erase_if(std::basic_string)  \fI(function template)\fP
   (C++20)
.SH Input/output
   operator<<                   performs stream input and output on strings
   operator>>                   \fI(function template)\fP
   getline                      read data from an I/O stream into a string
                                \fI(function template)\fP
.SH Numeric conversions
   stoi
   stol
   stoll                        converts a string to a signed integer
   \fI(C++11)\fP                      \fI(function)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   stoul
   stoull                       converts a string to an unsigned integer
   \fI(C++11)\fP                      \fI(function)\fP
   \fI(C++11)\fP
   stof
   stod
   stold                        converts a string to a floating point value
   \fI(C++11)\fP                      \fI(function)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   to_string                    converts an integral or floating-point value to string
   \fI(C++11)\fP                      \fI(function)\fP
   to_wstring                   converts an integral or floating-point value to wstring
   \fI(C++11)\fP                      \fI(function)\fP

.SH Literals

   Defined in inline namespace std::literals::string_literals
   operator""s   converts a character array literal to basic_string
   \fI(C++14)\fP       \fI(function)\fP

.SH Helper classes

   std::hash<std::basic_string> hash support for strings
   \fI(C++11)\fP                      \fI(class template specialization)\fP

   Deduction guides \fI(since C++17)\fP

.SH Notes

   Although it is required that customized construct or destroy is used when
   constructing or destroying elements of std::basic_string until C++23, all
   implementations only used the default mechanism. The requirement is corrected by
   P1072R10 to match existing practice.

            Feature-test macro            Value    Std              Feature
   __cpp_lib_string_udls                 201304L \fI(C++14)\fP User-defined literals for
                                                         string types
   __cpp_lib_starts_ends_with            201711L (C++20) starts_with, ends_with
   __cpp_lib_constexpr_string            201907L (C++20) Constexpr for
                                                         std::basic_string
   __cpp_lib_char8_t                     201907L (C++20) std::u8string
   __cpp_lib_erase_if                    202002L (C++20) erase, erase_if
   __cpp_lib_string_contains             202011L (C++23) contains
   __cpp_lib_string_resize_and_overwrite 202110L (C++23) resize_and_overwrite
                                                         Member functions for
   __cpp_lib_containers_ranges           202202L (C++23) construction, insertion, and
                                                         replacement that accept
                                                         container compatible range

.SH Example


// Run this code

 #include <iostream>
 #include <string>

 int main()
 {
     using namespace std::literals;

     // Creating a string from const char*
     std::string str1 = "hello";

     // Creating a string using string literal
     auto str2 = "world"s;

     // Concatenating strings
     std::string str3 = str1 + " " + str2;

     // Print out the result
     std::cout << str3 << '\\n';

     std::string::size_type pos = str3.find(" ");
     str1 = str3.substr(pos + 1); // the part after the space
     str2 = str3.substr(0, pos);  // the part till the space

     std::cout << str1 << ' ' << str2 << '\\n';

     // Accessing an element using subscript operator[]
     std::cout << str1[0] << '\\n';
     str1[0] = 'W';
     std::cout << str1 << '\\n';
 }

.SH Output:

 hello world
 world hello
 w
 World

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR     Applied to            Behavior as published              Correct behavior
                        contiguity of the storage for elements of
   LWG 530   C++98      basic_string                                 required again
                        was accidently made not required by LWG259
                        the behavior is undefined if any of          the program is
   LWG 2994  C++98      Traits::char_type^[1]                        ill-formed in this
   (P1148R0)            and Allocator::char_type is different from   case
                        CharT

    1. ↑ The Traits::char_type case is fixed in P1148R0.

.SH See also

   basic_string_view read-only string view
   \fI(C++17)\fP           \fI(class template)\fP

.SH External links

   C++ string handling

.SH Hidden category:
     * Pages with unreviewed LWG DR marker
